home *** CD-ROM | disk | FTP | other *** search
/ EnigmA Amiga Run 1997 May / EnigmA AMIGA RUN 18 (1997)(G.R. Edizioni)(IT)[!][issue 1997-05][EAR-CD II].iso / softwareupdate / system / amigados / miscellaneous / miscellaneous.doc < prev    next >
Text File  |  1996-10-10  |  12KB  |  358 lines
  1. 8    MISCELLANEOUS
  2.  
  3. 8.1  INTRODUCTION
  4.  
  5. In this chapter I will describe some very useful AmigaDOS
  6. functions which did not fit in the other chapters. Although
  7. some knowledge about AmigaDOS is required to understand this
  8. chapter you do not have to read all previous chapters before
  9. this one. The introduction chapter should be enough.
  10.  
  11. The following subjects will be described:
  12.  
  13.   1. The Global Error Code
  14.   2. How to execute "Shell" commands from a C program
  15.   
  16.   Not much for the moment, but more will soon be added!!!
  17.  
  18.  
  19.  
  20. 8.2  THE GLOBAL ERROR CODE
  21.  
  22. When a dos function fails it will usually store some
  23. information about the error, an error code, in a special global
  24. variable. You can get a copy of this error code with the help
  25. of the IoErr() function.
  26.  
  27. There are three good reasons why you should call the IoErr()
  28. function when you encounter a dos error:
  29.  
  30.   1. First you need to inform the user and it is then of course
  31.      good to know what really have happened so you can tell the
  32.      user to take appropriate action.
  33.  
  34.   2. The more your program knows about the error the easier it
  35.      is for your program to solve it.
  36.  
  37.   3. Some times you need to check if it really was an error or
  38.      not when a dos function failed. For example, in the
  39.      previous chapter you read about how to list all objects in
  40.      a directory. When no more objects can be found the
  41.      function, ExNext(), will fail. This is usually not any
  42.      "real" error since there are of course a limited number of
  43.      objects in a directory, and that dos function should
  44.      "fail" when all objects have been listed. It is in these
  45.      situations you have to check what the actual error was -
  46.      if there were not any more objects in the directory it is
  47.      OK, but if it was something else which caused the function
  48.      to fail there was a "real" error.
  49.  
  50. The IoErr() function is defined like this:
  51.  
  52. ---------------------------------------------------------------
  53.  
  54. IoErr()
  55.  
  56. ROM library: "dos.library/IoErr", (Any Version)
  57. #include <clib/dos_protos.h>
  58.  
  59. Returns the last AmigaDOS error message.
  60.  
  61. Synopsis:     error_code = IoErr();
  62.  
  63.   error_code: (LONG) The function will return one of the below
  64.               listed error flags: (The flags are defined in
  65.               header file "dos/dos.h")
  66.  
  67.               ERROR_NO_FREE_STORE:
  68.                 Out of memory!
  69.               ERROR_TASK_TABLE_FULL: 
  70.                 To many processes running!
  71.               ERROR_BAD_TEMPLATE: 
  72.                 Incorrect command line template!
  73.               ERROR_BAD_NUMBER: 
  74.                 Incorrect number/value!
  75.               ERROR_REQUIRED_ARG_MISSING: 
  76.                 Required arguemnt was not set!
  77.               ERROR_KEY_NEEDS_ARG: 
  78.                 The argument after the keyword is missing!
  79.               ERROR_TOO_MANY_ARGS: 
  80.                 Too many arguments on the command line!
  81.               ERROR_UNMATCHED_QUOTES: 
  82.                 Incorrect number of quotations!
  83.               ERROR_LINE_TOO_LONG: 
  84.                 Too long command line!
  85.               ERROR_FILE_NOT_OBJECT: 
  86.                 The file can not be found and/or executed
  87.               ERROR_INVALID_RESIDENT_LIBRARY: 
  88.                 The AmigaDOS library is too old!
  89.               ERROR_NO_DEFAULT_DIR: 
  90.                 There does not exist a default directory!
  91.               ERROR_OBJECT_IN_USE: 
  92.                 The object is currently used and is locked!
  93.               ERROR_OBJECT_EXISTS: 
  94.                 The object already exist and can not be deleted!
  95.               ERROR_DIR_NOT_FOUND: 
  96.                 Unknown directory!
  97.               ERROR_OBJECT_NOT_FOUND: 
  98.                 Unknown file or device!
  99.               ERROR_BAD_STREAM_NAME: 
  100.                 The string contained invalid commands/parameters!
  101.               ERROR_OBJECT_TOO_LARGE: 
  102.                 The object is too big!
  103.               ERROR_ACTION_NOT_KNOWN: 
  104.                 Impossible command used on a device!
  105.               ERROR_INVALID_COMPONENT_NAME: 
  106.                 Too long name or invalid signs used!
  107.               ERROR_INVALID_LOCK: 
  108.                 Invalid type of lock used!
  109.               ERROR_OBJECT_WRONG_TYPE: 
  110.                 Incorrect object type used!
  111.               ERROR_DISK_NOT_VALIDATED: 
  112.                 The disk has not yet been validated or is damaged!
  113.               ERROR_DISK_WRITE_PROTECTED: 
  114.                 The disk is write protected!
  115.               ERROR_RENAME_ACROSS_DEVICES: 
  116.                 Can not rename an object to another device!
  117.               ERROR_DIRECTORY_NOT_EMPTY: 
  118.                 Can not delete the directory since it is not empty!
  119.               ERROR_TOO_MANY_LEVELS: 
  120.                 Too many soft links used!
  121.               ERROR_DEVICE_NOT_MOUNTED: 
  122.                 Device not available!
  123.               ERROR_SEEK_ERROR: 
  124.                 Tried to move the file cursor outside the file!
  125.               ERROR_COMMENT_TOO_BIG: 
  126.                 Too long comment used!
  127.               ERROR_DISK_FULL: 
  128.                 The disk is full!
  129.               ERROR_DELETE_PROTECTED: 
  130.                 The object is protected from being deleted!
  131.               ERROR_WRITE_PROTECTED: 
  132.                 The object is protected from being overwritten
  133.               ERROR_READ_PROTECTED: 
  134.                 The object is protected from being read!
  135.               ERROR_NOT_A_DOS_DISK: 
  136.                 The disk is not of AmigaDOS format!
  137.               ERROR_NO_DISK: 
  138.                 No disk in the drive!
  139.               ERROR_NO_MORE_ENTRIES: 
  140.                 No more objects in the directory!
  141.  
  142.               ERROR_IS_SOFT_LINK: 
  143.                 Can not do it on a soft link!
  144.               ERROR_OBJECT_LINKED: 
  145.                 The object is linked!
  146.               ERROR_BAD_HUNK: 
  147.                 Incorect hunk found!
  148.               ERROR_NOT_IMPLEMENTED: 
  149.                 The feature has not been implemented yet!
  150.               ERROR_RECORD_NOT_LOCKED: 
  151.                 The record was not locked!
  152.               ERROR_LOCK_COLLISION: 
  153.                 Two locks collided!
  154.               ERROR_LOCK_TIMEOUT: 
  155.                 The time to get the lock has expired!
  156.               ERROR_UNLOCK_ERROR: 
  157.                 Problems with unlocking the object!
  158.  
  159.               ERROR_BUFFER_OVERFLOW:
  160.                 Some internal buffer was too small!
  161.               ERROR_BREAK:
  162.                 The executin was stopped!
  163.               ERROR_NOT_EXECUTABLE:
  164.                 The file is protected from being executed!
  165.  
  166. Please note that all dos function does not use the global error
  167. code! You should therefore, of course, only use it when you
  168. have been told that it will work.
  169.  
  170. Here is a simple example on how to use the IoErr() function:
  171.  
  172.   /* Store the error code here: */
  173.   LONG error_code;
  174.  
  175.   - - -
  176.  
  177.   /* Collect the global error code: */
  178.   error_code = IoErr();
  179.  
  180.   /* Print the error code: */
  181.   printf( "Error code: %d - ", error_code );
  182.  
  183.   /* Examine the error code: */  
  184.   switch( error_code )
  185.   {
  186.     case ERROR_NO_FREE_STORE: printf( "Out of memory!\n" ); break;
  187.     case ERROR_TASK_TABLE_FULL: printf( "To many processes running!\n" ); 
  188. break;
  189.  
  190.     /* and so on... */
  191.  
  192.     default:
  193.       printf( "Unknown error reported!\n" );
  194.   }
  195.  
  196.  
  197. See also: SetIoErr()
  198.  
  199. ---------------------------------------------------------------
  200.  
  201. Some dos functions, FRead() and FWrite(), were badly written
  202. and do not "clear" the error code before they are executed. It
  203. is therefore impossible to know if the value in the global
  204. error variable is valid after you have executed these
  205. functions - it might be an old value in the global error
  206. variable.
  207.  
  208. To solve this problem you must therefore "clear" the global
  209. error variable yourself (set the variable to 0) before you
  210. execute these badly written functions. 
  211.  
  212. To alter the global error variable simply call the "SetIoErr()"
  213. function.
  214.  
  215. ---------------------------------------------------------------
  216.  
  217. SetIoErr()
  218.  
  219. ROM library: "dos.library/SetIoErr", (V36+)
  220. #include <clib/dos_protos.h>
  221.  
  222. Alters the global dos error variable.
  223.  
  224. Synopsis:    old_value = SetIoErr( new_value );
  225.   
  226.   old_value: (LONG) The function will return the "old" error
  227.              value. See "IoErr()" for more information about
  228.              the possible error codes.
  229.  
  230.   new_value: (LONG) The new value you want to store in the
  231.              global error variable. When you want to "clear"
  232.              the variable you should set this field to 0.
  233.  
  234. Here is a simple example on how to use the SetIoErr() function:
  235.  
  236.   /* Store the "old" error code here: */
  237.   LONG old_error_code;
  238.  
  239.   - - -
  240.  
  241.   /* Set the global error variable to 0: */
  242.   /* ("Clear" the global error variable) */
  243.   old_error_code = SetIoErr( 0 );
  244.  
  245.   /* Print the "old" error code: */
  246.   printf( "Old error code: %d\n", old_error_code );
  247.  
  248.  
  249. See also: IoErr()
  250.  
  251. ---------------------------------------------------------------
  252.  
  253. Although your own program also can use this global error
  254. variable with the help of SetIoErr() and IoErr(), it is not
  255. recommended. It is better to use your own variables if needed.
  256.  
  257.  
  258.  
  259. 8.3  HOW TO EXECUTE "SHELL" COMMANDS FROM A C PROGRAM
  260.  
  261. You can execute "Shell" commands from C with the help of the
  262. "Execute()" function. Indeed, you can actually execute any
  263. type of programs (not only the standard commands like "dir",
  264. "list", "type" etc...) which you can access from the "Shell".
  265.  
  266. ---------------------------------------------------------------
  267.  
  268. Execute()
  269.  
  270. ROM library: "dos.library/Execute", (Any Version)
  271. #include <clib/dos_protos.h>
  272.  
  273. Executes "Shell" commands from C.
  274.  
  275. Synopsis:     ok = Execute( com_str, def_input, def_output );
  276.   
  277.   ok:         (LONG) If the command could successfully be
  278.               launched TRUE will be returned, else FALSE is
  279.               returned.
  280.               
  281.               Please note that the function will not wait for
  282.               the executed program to be completed, and the
  283.               function can consequently not know if the
  284.               executed program finished its task successfully
  285.               or failed. The returned value indicates only if
  286.               the program was successfully started (launched)
  287.               or not.
  288.  
  289.   com_str:    (STRPTR) Pointer to a string which contains the
  290.               command line you want to have executed. Here are
  291.               some examples:
  292.                 "Dir"
  293.                 "C:Dir RAM: All" 
  294.                 "C:Copy DH0:Car.doc to DF1:"
  295.                 "MyPaintProg Flowers.pic"
  296.  
  297.   def_input:  (BPTR) Pointer to the "default input handler".
  298.               This filed is usually set to NULL, since a
  299.               default input handler is usually not needed.
  300.  
  301.               See chapter 6 "Handlers" for more information
  302.               about handlers.
  303.  
  304.   def_output: (BPTR) Pointer to the "default output handler".
  305.  
  306.               See chapter 6 "Handlers" for more information
  307.               about handlers.
  308.               
  309.               If the program you executed do not use the
  310.               default output handler you can set this field
  311.               to NULL.
  312.  
  313. Note! The "run" program must be available in the "C:" directory
  314. if you use Execute() with dos library V34 or earlier.
  315.  
  316. Here is a simple example on how to use the Execute() function:
  317.  
  318.   /* Store the result code here: */
  319.   BOOL ok;
  320.   
  321.   /* A "BCPL" pointer to our "default output */
  322.   /* handler": (a Console Window)            */
  323.   BPTR my_console;
  324.  
  325.   - - -
  326.  
  327.   /* Open a Console Window which will be used as our */
  328.   /* default output handler:                         */
  329.   my_console = 
  330.    Open( "CON:0/0/640/100/Test/CLOSE/WAIT", MODE_NEWFILE );
  331.  
  332.   /* Have we successfully opened the Console Window? */
  333.   if( !my_console )
  334.     exit( 20 ); /* Exit with an error code: */
  335.  
  336.   
  337.   /* Execute the "Shell" command "Dir". We do not use */
  338.   /* and "input" handler, and the "output" should be  */
  339.   /* sent to our Console Window.                      */
  340.   ok = Execute( "C:Dir RAM:", NULL, my_console );
  341.  
  342.   /* OK? */
  343.   if( ok )
  344.     printf( "The \"Shell\" command was successfully executed!\n" );
  345.   else
  346.     printf( "Error! Could not execute the \"Shell\" command!\n" );
  347.  
  348.   - - -
  349.  
  350.   /* Close the Console Window: */
  351.   Close( my_console );
  352.  
  353.  
  354. See also: Open(), Close()
  355.  
  356. ---------------------------------------------------------------
  357.  
  358.